Make the shell scripts runnable, and have them find a Python 3 - #137

Summary

• test.sh, run.sh and format.sh are given a real #!/bin/bash shebang in place of the commented-out # /bin/bash, and the executable bit is set on all three, so the ./<name>.sh invocation each one documents in its own usage line works on a fresh clone instead of failing with Permission denied.
• test.sh and run.sh no longer hardcode python. An interpreter is resolved first: the first of python3, then python, that reports 3.8 or newer — the minimum README states — is taken, and a PYTHON environment variable set beforehand overrides the choice so a virtualenv interpreter can be pointed at directly. When no candidate qualifies, a plain message is printed and the script exits 1, rather than the run proceeding under Python 2.7 and surfacing as a conftest ImportError for pygame.
• The commands documented in README.md and in the comment at requirements.txt:2 are spelled python3, and the interpreter-resolution behaviour and the PYTHON override are documented in README's usage section.
• The coverage artifacts test.sh writes (.coverage, cov.xml) are added to .gitignore. This is adjacent rather than named by the issue, and is included deliberately: with ./test.sh now runnable on a fresh clone, the project's only verification gate would otherwise leave two untracked files in the tree every time it is run — the same class of stray-artifact leak that commit ad85816 had to undo.
• tests/test_shell_scripts.py is added as a regression guard, since none of the above is exercised by the existing suite. The resolver is run rather than pattern-matched: its function body is lifted out of the script under test and executed against fake python3/python executables that report whatever version a case needs, with PATH holding nothing else. Preference order, the fallback to python, the PYTHON override, the version floor and the failure exit are each observed. The floor is parsed out of README, so the scripts and the requirement they implement cannot drift apart quietly. The shebang, the executable bit, and the fact that every line running pytest or the game goes through "$PYTHON" are asserted statically alongside.

Test plan

• python3 -m pytest — 306 passed, 0 failed (289 before this change, plus 17 new script tests). ./test.sh itself could not be invoked in the session this change was prepared in — the sandbox refuses to execute repository shell scripts — so the command test.sh issues was run directly instead.
• Coverage was not regressed: no file under src/ is touched by this change, and total coverage is unchanged at 87%.
• Regression evidence, empirically confirmed rather than reasoned: with test.sh, run.sh, format.sh, README.md and requirements.txt restored to their origin/main state and the new test file left in place, 16 of the 17 new tests FAIL (the seventeenth is a bash -n syntax check, which the old scripts also pass); with the change restored, all 17 PASS.
• Two mutations were introduced to confirm the behavioural tests bite rather than merely accompany the change. Relaxing the floor to (3, 0) fails test_the_documented_minimum_version_is_the_one_enforced[test.sh] and nothing else; reversing the candidate order to python python3 fails test_the_newest_qualifying_candidate_is_preferred[test.sh] and nothing else. Both mutations were then reverted and the suite reconfirmed green.
• Staged content was checked for stray artifacts: no __pycache__, .pyc, save.json, output.txt, .coverage, cov.xml or .claude/ path is included, and the three scripts are recorded in the index at mode 100755.
• A one-off ./test.sh and ./run.sh on an ordinary machine is still worth doing before merge, since the end-to-end invocation is the one thing the sandbox could not cover and this repository has no CI workflow to cover it either.

Notes

• No file under src/ is modified, so no player-facing behaviour changes and the UI-parity question between the pygame and text interfaces does not arise here.
• The commented-out checkDependencies block in run.sh still mentions bare python; it is dead code and was left untouched to keep the diff to the issue's scope.
• tests/test_shell_scripts.py does not mirror a module under src/ the way every other test file does, because the code it covers is not Python. It is placed at the top level of tests/ alongside the other non-package test files.

Deferred this cycle

The rest of the open backlog was not picked up, for these reasons:

• The obituary screen does not report the score of the run that just ended #136 (obituary screen does not report the run's score) and Score and tick count reset on every level-up, so a run is recorded with only its final level's score #122 (score and tick count reset on every level-up) are gameplay/state bugs in src/, and are plausibly coupled to each other — batching either with a shell-script and documentation fix would have mixed unrelated concerns in one review. They are good candidates for the next cycle, taken together.
• Implement High Score System and Display #80, Add Menu Transitions and Animations #79, Create Key Binding Configuration Interface #78, Add Settings Configuration System #77, Implement Basic Menu System Framework #76 (high-score system, menu framework, settings, key-binding UI, menu transitions) are feature work well beyond a polish-sized PR; Implement Basic Menu System Framework #76 is a prerequisite for several of the others.
• Add Power-up Sound Effects #75 (power-up sound effects) adds a new asset and audio subsystem, which is outside a scripts-and-docs cycle.
• Integrate Viron support #52 (Viron integration) requires registering an external submodule, which needs separate authorization and cannot be attempted autonomously.

Four pull requests were already open at triage — #59 (develop, conflicting), and Copilot drafts #98, #96 and #90 (two conflicting) — all between nine and fourteen months stale and authored elsewhere. None was opened by this loop, so none was adopted or closed here; a decision on them belongs to a human.

Closes #135

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

drafted by Claude on behalf of Daniel Stephenson